<?php
/*
 * Copyright (c) 2008 Sergey Bondari, bondari@bondari.net
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - The name of the author may not be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

namespace Mosaic\System;


/**
 * Generic resource interface
 *
 * Any component resource must implement this interface
 *
 * @package System
 */
interface ifResourceInfo {
	/**
	 * Resource type URN
	 * @return string
	 */
	public function getType();


	/**
	 * Prepares resource
	 *
	 * Optional action. For example it loads the file.
	 *
	 * @return void
	 */
	public function prepare();


	/**
	 * Gets resource instance key
	 *
	 * @return void
	 */
	public function key();

	/**
	 * Creates resource key
	 *
	 * Resource key is the unique resource instance identification. 
	 * Usually consists of URN and name
	 *
	 * @return void
	 */
	public static function createKey($systemID);


	/**
	 * Creates resource instance 
	 *
	 * @return ifResourceInfo
	 */
	public static function create($systemID, $data);
}


/**
 * Generic component interface
 *
 * Any system component must implement this interface
 *
 * @package System
 */
interface ifComponent {


	/**
	 * Component information component instance getter
	 * @return ComponentInfo
	 */
	public function componentInfo();

	/**
	 * Component deinitialization routine
	 * @return ComponentInfo
	 */
	public function __stop();

}


/**
 * Remote component interface
 *
 * A remote component stub interface
 *
 * @package System
 */
interface ifRemoteComponent extends ifComponent {

	/**
	 * Node name getter		
	 * @return string Node name
	 */
	public function getNodeName();

}

/**
 * Event handler interface
 *
 * Any event handling component must imlement this interface
 *
 * @package System
 */
interface ifEventHandler extends ifComponent {

	/**
	 * Event processing entry function
	 * @param ifEvent Event to process
	 */
	public function onEvent(ifEvent $event);

}


/**
 * Tile processing component interface
 *
 * Any tile processing component must imlement this interface
 *
 * @package System
 */
interface ifTileParser extends ifComponent {

	/**
	 * Tile processing entry function
	 * Function is required to echo XML that is a result of processing.
	 * @param ifTile Tile to process
	 */
	public function onTileParse(ifTile $tile);

}





/**
 * Kernel module interface
 *
 * Any kernel module component must imlement this interface
 *
 * @package System
 */
interface ifKModule extends ifComponent {

	/**
	 * Kernel module initialiaztion routine
	 * @return void
	 */
	public function onKModuleInit();

}

/**
 * Entity that requires execution context synchronization during its processing.
 *
 * @package System
 */
interface ifContextSwitcher {

	/**
	 * Preserve context tag
	 * @var string Context tag
	 * @return void
	 */
	public function setContextTag($tag);

	/**
	 * Get context tag to synchronize with
	 * @return string Context tag
	 */
	public function getContextTag();
}



/**
 * Interface for generic system request/response 
 *
 * Any system request/response must implement this interface
 *
 * @package System
 */
interface ifRequestEntity extends ifContextSwitcher {
	/**
	 * Create MCGI packet from instance
	 *
	 * @return \Mosaic\MCGI\Packet
	 */
	public function createMCGIPacket();

	/**
	 * Create instance from MCGI packet
	 *
	 * @param \Mosaic\MCGI\Packet
	 * @return ifResourceEntity
	 */
	public static function createFromMCGIPacket(\Mosaic\MCGI\Packet $mcgi);

	/**
	 * Gets request token of instance
	 *
	 * @return string Request token
	 */
	public function getRequestToken();

}


/**
 * Resource instance container 
 *
 * @package System
 */
interface ifResource extends ifContextSwitcher {
	/**
	 * Adds a new callback into callback stack
	 * @param mixed callback
	 * @return void
	 */
	public function pushCallback($cb);

	/**
	 * Returns event callback from the stack top
	 * @return mixed callback
	 */
	public function popCallback();

	
	/**
	 * Indicates if there are some callbacks left in stack
	 * @return boolean true if there are callbacks
	 */
	public function hasCallback();
}


/**
 * Event interface
 *
 * System event interface
 *
 * @package System
 */
interface ifEvent extends ifResource {
	/**
	 * Stops the event execution
	 */
	public function cancel();


	/**
	 * Returns the event name
	 * @return string
	 */
	public function getName();

	/**
	 * Returns the event name
	 * @return string
	 */
	public function __toString();

}

/**
 * Tile interface
 *
 * System event interface
 *
 * @package System
 */
interface ifTile extends ifResource {
	/**
	 * Sets parsed data from XML
	 * @param string
	 */
	public function setParsedXML($xml);

	/**
	 * Returns the tile XML to parse
	 * @return string
	 */
	public function getXML();

	/**
	 * Returns the tile DOM node reference
	 * @return DOMNode
	 */
	public function getDOM();

	/**
	 * Returns the tile tag name
	 * @return string
	 */
	public function getTagName();

	/**
	 * Returns the tile attributes
	 * @return array
	 */
	public function getAttributes();

}



/**
 * Serializable object
 *
 * @package System
 */
interface ifSerializable {
	/**
	 * @return string
	 */
	public function serialize();
	
	/**
	 * @param string
	 * @return ifSerializable
	 */
	static public function deserialize($string);
}
